Inside Macintosh: Imaging With QuickDraw /: Chapter 7 - Pictures

Summary of Pictures and the Picture Utilities

Pascal Summary

Constants

CONST
   {color-picking methods}
   systemMethod   = 0;  {let Picture Utilities choose the method (currently }
                        { they always choose popularMethod)}
   popularMethod  = 1;  {return most frequently used colors}
   medianMethod   = 2;  {return a weighted distribution of colors}

   {picture information to be returned by Picture Utilities}
   returnColorTable        = 1;  {return a ColorTable record}
   returnPalette           = 2;  {return a Palette record}
   recordComments          = 4;  {return comment information}
   recordFontInfo          = 8;  {return font information}
   suppressBlackAndWhite   = 16; {don't include black and }
                                 { white with returned colors}

   {color bank types}
   colorBankIsCustom       = -1; {gathers colors into a custom color bank}
   colorBankIsExactAnd555  = 0;  {gathers exact colors if there are less }
                                 { than 256 unique colors in picture; }
                                 { otherwise gathers colors for picture }
                                 { in a 5-5-5 histogram}
   colorBankIs555          = 1;  {gathers colors in a 5-5-5 histogram}

Data Types

TYPE
   PicPtr      = ^Picture;
   PicHandle   = ^PicPtr;
   Picture     = 
   RECORD                  {picture record}
      picSize:    Integer; {for a version 1 picture: its size}
      picFrame:   Rect;    {bounding rectangle for the picture}
      {variable amount of picture data in the form of opcodes}
   END;
OpenCPicParams = 
   RECORD
      srcRect:    Rect;       {optimal bounding rectangle for displaying }
                              { picture at resolution indicated in hRes, }
                              { vRes fields}
      hRes:       Fixed;      {best horizontal resolution; }
                              { $00480000 specifies 72 dpi}
      vRes:       Fixed;      {best vertical resolution; }
                              { $00480000 specifies 72 dpi}
      version:    Integer;    {set to -2}
      reserved1:  Integer;    {reserved; set to 0}
      reserved2:  LongInt;    {reserved; set to 0}
   END;
CommentSpecHandle = ^CommentSpecPtr;
   CommentSpecPtr    = ^CommentSpec;
   CommentSpec       =     {comment specification record}
   RECORD
      count:   Integer;    {number of times this type of comment }
                           { occurs in the picture or survey}
      ID:      Integer;    {value identifying this type of comment}
   END;
FontSpecHandle = ^FontSpecPtr;
   FontSpecPtr    = ^FontSpec;
   FontSpec       =           {font specification record}
   RECORD
      pictFontID: Integer;    {font ID as stored in the picture}
      sysFontID:  Integer;    {font family ID}
      size:       ARRAY[0..3] OF LongInt; 
                              {each bit set from 1 to 127 indicates a }
                              { point size at that value; if bit 0 is }
                              { set, then a size larger than 127 }
                              { points is found}
      style:      Integer;    {styles used for this font family}
      nameOffset: LongInt;    {offset to font name stored in the }
                              { data structure indicated by the }
                              { fontNamesHandle field of the PictInfo }
                              { record}
   END;
PictInfoID     = LongInt;
PictInfoHandle = ^PictInfoPtr;
   PictInfoPtr    = ^PictInfo;
   PictInfo       =                       {picture information record}
   RECORD
      version:          Integer;          {Picture Utilities version number}
      uniqueColors:     LongInt;          {total colors in survey}
      thePalette:       PaletteHandle;    {handle to a Palette record--NIL }
                                          { for a bitmap in a basic }
                                          { graphics port}
      theColorTable:    CTabHandle;       {handle to a ColorTable record-- }
                                          { NIL for a bitmap in a basic }
                                          { graphics port}
      hRes:             Fixed;            {best horizontal resolution (dpi)}
      vRes:             Fixed;            {best vertical resolution (dpi)}
      depth:            Integer;          {greatest pixel depth}
      sourceRect:       Rect;             {optimal bounding rectangle for }
                                          { picture for display at }
                                          { resolution specified in hRes }
                                          { and vRes fields}
      textCount:        LongInt;          {number of text strings in }
                                          { picture(s)}
      lineCount:        LongInt;          {number of lines in picture(s)}
      rectCount:        LongInt;          {number of rectangles in }
                                          { picture(s)}
      rRectCount:       LongInt;          {number of rounded rectangles in }
                                          { picture(s)}
      ovalCount:        LongInt;          {number of ovals in picture(s)}
      arcCount:         LongInt;          {number of arcs and wedges in }
                                          { picture(s)}
      polyCount:        LongInt;          {number of polygons in picture(s)}
      regionCount:      LongInt;          {number of regions in picture(s)}
      bitMapCount:      LongInt;          {number of bitmaps}
      pixMapCount:      LongInt;          {number of pixel maps}
      commentCount:     LongInt;          {number of comments in picture(s)}
      uniqueComments:   LongInt;          {number of different comments }
                                          { (by ID) in picture(s)}
      commentHandle:    CommentSpecHandle;
                                          {handle to array of CommentSpec }
                                          { records for picture(s)}
      uniqueFonts:      LongInt;          {number of fonts in picture(s)}
      fontHandle:       FontSpecHandle;   {handle to an array of FontSpec }
                                          { records for picture(s)}
      fontNamesHandle:  Handle;           {handle to list of font names for }
                                          { picture(s)}
      reserved1:        LongInt;
      reserved2:        LongInt;
   END;

Routines

Creating and Disposing of Pictures

FUNCTION OpenCPicture     (newHeader: OpenCPicParams): PicHandle;
FUNCTION OpenPicture      (picFrame: Rect): PicHandle;
PROCEDURE PicComment      (kind,dataSize: Integer; dataHandle: Handle);
PROCEDURE ClosePicture;
PROCEDURE KillPicture     (myPicture: PicHandle);

Drawing Pictures

PROCEDURE DrawPicture     (myPicture: PicHandle; dstRect: Rect);
FUNCTION GetPicture       (picID: Integer): PicHandle;

Collecting Picture Information

/* DisposePictInfo is also spelled as DisposPictInfo */
FUNCTION GetPictInfo      (thePictHandle: PicHandle; 
                           VAR thePictInfo: PictInfo; verb: Integer; 
                           colorsRequested: Integer; 
                           colorPickMethod: Integer; 
                           version: Integer): OSErr;
FUNCTION GetPixMapInfo    (thePixMapHandle: PixMapHandle; 
                           VAR thePictInfo: PictInfo; verb: Integer; 
                           colorsRequested: Integer; 
                           colorPickMethod: Integer; 
                           version: Integer): OSErr;
FUNCTION NewPictInfo      (VAR thePictInfoID: PictInfoID; verb: Integer; 
                           colorsRequested: Integer; 
                           colorPickMethod: Integer; 
                           version: Integer): OSErr;
FUNCTION RecordPictInfo   (thePictInfoID: PictInfoID; 
                           thePictHandle: PicHandle): OSErr;
FUNCTION RecordPixMapInfo (thePictInfoID: PictInfoID; 
                           thePixMapHandle: PixMapHandle): OSErr;
FUNCTION RetrievePictInfo (thePictInfoID: PictInfoID; 
                           VAR thePictInfo: PictInfo; 
                           colorsRequested: Integer): OSErr;
FUNCTION DisposePictInfo  (thePictInfoID: PictInfoID): OSErr;

Application-Defined Routines

FUNCTION MyInitPickMethod (colorsRequested: Integer; 
                           VAR dataRef: LongInt; 
                           VAR colorBankType: Integer): OSErr;
FUNCTION MyRecordColors   (dataRef: LongInt; colorsArray: RGBColorArray; 
                           colorCount: LongInt; 
                           VAR uniqueColors: LongInt): OSErr;
FUNCTION MyCalcColorTable (dataRef: LongInt; colorsRequested: Integer; 
                           colorBankPtr: Ptr; 
                           VAR resultPtr: CSpecArray): OSErr;
FUNCTION MyDisposeColorPickMethod
                          (dataRef: LongInt): OSErr;

C Summary

Constants

/* color-picking methods */
#define systemMethod    0  /* let Picture Utilities choose the method 
                              (currently they always choose popularMethod) */
#define popularMethod   1  /* return most frequently used colors */
#define medianMethod    2  /* return a weighted distribution of colors */
/* picture information to be returned by Picture Utilities */
#define returnColorTable   ((short) 0x0001)  /* return a ColorTable record */
#define returnPalette      ((short) 0x0002)  /* return a Palette record */
#define recordComments     ((short) 0x0004)  /* return comment information */
#define recordFontInfo     ((short) 0x0008)  /* return font information */
#define suppressBlackAndWhite
                           ((short) 0x0010)  /* don't include black and 
                                                white with returned colors */
/* color bank types */
#define ColorBankIsCustom        -1    /* gathers colors into a custom 
                                          color bank */
#define ColorBankIsExactAnd555   0     /* gathers exact colors if there are 
                                          less than 256 unique colors in
                                          picture; otherwise gathers colors 
                                          for picture in a 5-5-5 histogram */
#define ColorBankIs555           1     /* gathers colors in a 5-5-5
                                          histogram */

Data Types

struct Picture {
   short    picSize;    /* for a version 1 picture: its size */
   Rect     picFrame;   /* bounding rectangle for the picture */
   /* variable amount of picture data in the form of opcodes */
};
typedef struct Picture Picture;
typedef Picture *PicPtr, **PicHandle;
struct OpenCPicParams {
   Rect  srcRect;    /* optimal bounding rectangle for displaying picture at
                        resolution indicated in hRes, vRes fields */
   Fixed hRes;       /* best horizontal resolution; $00480000 specifies 
                        72 dpi */
   Fixed vRes;       /* best vertical resolution; $00480000 specifies 
                        72 dpi */
   short version;    /* set to -2 */
   short reserved1;  /* reserved; set to 0 */
   long  reserved2;  /* reserved; set to 0 */
};
struct CommentSpec {
   short    count;   /* number of times this type of comment occurs in  
                        the picture or survey */
   short    ID;      /* value identifying this type of comment */
};
typedef struct CommentSpec CommentSpec;
typedef CommentSpec *CommentSpecPtr, **CommentSpecHandle;
struct FontSpec {       /* font specification record */
   short    pictFontID; /* font ID as stored in the picture */
   short    sysFontID;  /* font family ID */
   long     size[4];    /* each bit set from 1 to 127 indicates a point
                           size at that value; if bit 0 is set, then a size
                           larger than 127 is found */
   short    style;      /* styles used for this font family */
   long     nameOffset; /* offset to font name stored in the data structure 
                           indicated by the fontNamesHandle field of the 
                           PictInfo record */
};
typedef struct FontSpec FontSpec;
typedef FontSpec *FontSpecPtr, **FontSpecHandle;
struct  PictInfo {
   short             version;       /* Picture Utilities version number */
   long              uniqueColors;  /* total colors in survey */
   PaletteHandle     thePalette;    /* handle to a Palette record--NIL for 
                                       a bitmap in a basic graphics port */
   CTabHandle        theColorTable; /* handle to a ColorTable record--NIL for 
                                       a bitmap in a basic graphics port */
   Fixed             hRes;          /* best horizontal resolution (dpi)} */
   Fixed             vRes;          /* best vertical resolution (dpi) */
   short             depth;         /* greatest pixel depth */
   Rect              sourceRect;    /* optimal bounding rectangle for  
                                       picture for display at resolution
                                       specified in hRes and vRes fields */
   long              textCount;     /* number of text strings in 
                                       picture(s) */
   long              lineCount;     /* number of lines in picture(s) */
   long              rectCount;     /* number of rectangles in picture(s) */
   long              rRectCount;    /* number of rounded rectangles in  
                                       picture(s) */
   long              ovalCount;     /* number of ovals in picture(s) */
   long              arcCount;      /* number of arcs and wedges in 
                                       picture(s) */
   long              polyCount;     /* number of polygons in picture(s) */
   long              regionCount;   /* number of regions in picture(s) */
   long              bitMapCount;   /* number of bitmaps */
   long              pixMapCount;   /* number of pixel maps */
   long              commentCount;  /* number of comments in picture(s) */
   long              uniqueComments;
                                    /* number of different comments (by ID) 
                                       in picture(s) */
   CommentSpecHandle commentHandle; /* handle to an array of CommentSpec 
                                       structures for picture(s) */
   long              uniqueFonts;   /* number of fonts in picture(s) */
   FontSpecHandle    fontHandle;    /* handle to an array of FontSpec 
                                       structures for picture(s) */ 
   Handle            fontNamesHandle;
                                    /* handle to list of font names for 
                                       picture(s) */
   long              reserved1;
   long              reserved2;
};
typedef struct PictInfo PictInfo;
typedef PictInfo *PictInfoPtr,**PictInfoHandle;
typedef long PictInfoID;

Functions

Creating and Disposing of Pictures

pascal PicHandle OpenCPicture
                            (const OpenCPicParams *newHeader); 
pascal PicHandle OpenPicture
                            (const Rect *picFrame); 
pascal void PicComment      (short kind, short dataSize, Handle dataHandle); 
pascal void ClosePicture    (void);
pascal void KillPicture     (PicHandle myPicture);

Drawing Pictures

pascal void DrawPicture     (PicHandle myPicture, const Rect *dstRect);
pascal PicHandle GetPicture (Integer picID);

Collecting Picture Information

pascal OSErr GetPictInfo    (PicHandle thePictHandle, 
                             PictInfo *thePictInfo, short verb, 
                             short colorsRequested, short colorPickMethod, 
                             short version);
pascal OSErr GetPixMapInfo  (PixMapHandle thePixMapHandle, 
                             pictInfo *thePictInfo, short verb, 
                             short colorsRequested, short colorPickMethod, 
                             short version);
pascal OSErr NewPictInfo    (PictInfoID *thePictInfoID, short verb,         
                             short colorsRequested, short colorPickMethod,
                             short version);
pascal OSErr RecordPictInfo (PictInfoID thePictInfoID, 
                             PicHandle thePictHandle);
pascal OSErr RecordPixMapInfo
                            (PictInfoID thePictInfoID, 
                             PixMapHandle thePixMapHandle);
pascal OSErr RetrievePictInfo
                            (PictInfoID thePictInfoID, 
                             PictInfo *thePictInfo, short colorsRequested);
pascal OSErr DisposePictInfo
                            (PictInfoID thePictInfoID);

Application-Defined Functions

pascal OSErr MyInitPickMethod
                            (short colorsRequested, long *dataRef, 
                             short *colorBankType);
pascal OSErr MyRecordColors (long dataRef, RGBColorArray colorsArray, 
                             long colorCount, long *uniqueColors);
pascal OSErr MyCalcColorTable
                            (long dataRef, short colorsRequested, 
                             Ptr colorBankPtr, CSpecArray *resultPtr);
pascal OSErr MyDisposeColorPickMethod
                            (long dataRef);

Assembly-Language Summary

Data Structures

Picture Data Structure
0 picSize word for a version 1 picture: its size
2 picFrame 8 bytes bounding rectangle for the picture
10 picData variable variable amount of picture data

OpenCPicParams Data Structure
0 srcRect 8 bytes optimal bounding rectangle for displaying picture at `hRes`, `vRes`
8 hRes long best horizontal resolution
12 vRes long best vertical resolution
16 version word always set to -2
18 reserved1 word reserved; set to 0
20 reserved2 long reserved; set to 0

CommentSpec Data Structure
0 count long number of times this type of comment occurs in picture or survey
4 ID long value identifying this type of comment

FontSpec Data Structure
0 pictFontID word font ID as stored in the picture
2 sysFontID word font family ID
4 size 8 bytes each bit set from 1 to 127 indicates a point size at that value; if bit 0 is set, then a size larger than 127 points is found
12 style word styles used for this font family
14 nameOffset long offset to font name stored in the data structure indicated by the `fontNamesHandle` field of the `PictInfo` record

PictInfo Data Structure
0 version word Picture Utilities version number
2 uniqueColors long total number of colors in survey
6 thePalette long handle to a Palette record--`NIL` for a bitmap in a basic graphics port
10 theColorTable long handle to a `ColorTable` record--`NIL` for a bitmap in a basic graphics port
14 hRes long best horizontal resolution (dpi)
18 vRes long best vertical resolution (dpi)
22 depth word greatest pixel depth
24 sourceRect 8 bytes optimal bounding rectangle for picture for display at resolution specified in `hRes` and `vRes` fields
32 textCount long number of text strings in picture(s)
36 lineCount long number of lines in picture(s)
40 rectCount long number of rectangles in picture(s)
44 rRectCount long number of rounded rectangles in picture(s)
48 ovalCount long number of ovals in picture(s)
52 arcCount long number of arcs and wedges in picture(s)
56 polyCount long number of polygons in picture(s)
60 regionCount long number of regions in picture(s)
64 bitMapCount long number of bitmaps
68 pixMapCount long number of pixel maps
72 commentCount long number of comments in picture(s)
76 uniqueComments long number of different comments (by ID) in picture(s)
80 commentHandle long handle to an array of `CommentSpec` records for picture(s)
84 uniqueFonts long number of fonts in picture(s)
88 fontHandle long handle to an array of `FontSpec` records for picture(s)
92 fontNamesHandle long handle to list of font names for picture(s)
96 reserved1 long reserved
100 reserved2 long reserved

Trap Macros

Trap Macros Requiring Routine Selectors

_Pack15

Selector	Routine
$0206	DisposePictInfo
$0403	RecordPictInfo
$0404	RecordPixMapInfo
$0505	RetrievePictInfo
$0602	NewPictInfo
$0800	GetPictInfo
$0801	GetPixMapInfo

Result Codes
pictInfoVersionErr -11000 Version number not 0
pictInfoIDErr -11001 Invalid picture information ID
pictInfoVerbErr -11002 Invalid verb combination specified
cantLoadPickMethodErr -11003 Custom pick method not in resource chain
colorsRequestedErr -11004 Number out of range or greater than that passed to `NewPictInfo`
pictureDataErr -11005 Invalid picture data

0	picSize	word	for a version 1 picture: its size
2	picFrame	8 bytes	bounding rectangle for the picture
10	picData	variable	variable amount of picture data

0	srcRect	8 bytes	optimal bounding rectangle for displaying picture at `hRes`, `vRes`
8	hRes	long	best horizontal resolution
12	vRes	long	best vertical resolution
16	version	word	always set to -2
18	reserved1	word	reserved; set to 0
20	reserved2	long	reserved; set to 0

0	count	long	number of times this type of comment occurs in picture or survey
4	ID	long	value identifying this type of comment

0	pictFontID	word	font ID as stored in the picture
2	sysFontID	word	font family ID
4	size	8 bytes	each bit set from 1 to 127 indicates a point size at that value; if bit 0 is set, then a size larger than 127 points is found
12	style	word	styles used for this font family
14	nameOffset	long	offset to font name stored in the data structure indicated by the `fontNamesHandle` field of the `PictInfo` record

0	version	word	Picture Utilities version number
2	uniqueColors	long	total number of colors in survey
6	thePalette	long	handle to a Palette record--`NIL` for a bitmap in a basic graphics port
10	theColorTable	long	handle to a `ColorTable` record--`NIL` for a bitmap in a basic graphics port
14	hRes	long	best horizontal resolution (dpi)
18	vRes	long	best vertical resolution (dpi)
22	depth	word	greatest pixel depth
24	sourceRect	8 bytes	optimal bounding rectangle for picture for display at resolution specified in `hRes` and `vRes` fields
32	textCount	long	number of text strings in picture(s)
36	lineCount	long	number of lines in picture(s)
40	rectCount	long	number of rectangles in picture(s)
44	rRectCount	long	number of rounded rectangles in picture(s)
48	ovalCount	long	number of ovals in picture(s)
52	arcCount	long	number of arcs and wedges in picture(s)
56	polyCount	long	number of polygons in picture(s)
60	regionCount	long	number of regions in picture(s)
64	bitMapCount	long	number of bitmaps
68	pixMapCount	long	number of pixel maps
72	commentCount	long	number of comments in picture(s)
76	uniqueComments	long	number of different comments (by ID) in picture(s)
80	commentHandle	long	handle to an array of `CommentSpec` records for picture(s)
84	uniqueFonts	long	number of fonts in picture(s)
88	fontHandle	long	handle to an array of `FontSpec` records for picture(s)
92	fontNamesHandle	long	handle to list of font names for picture(s)
96	reserved1	long	reserved
100	reserved2	long	reserved

pictInfoVersionErr	-11000	Version number not 0
pictInfoIDErr	-11001	Invalid picture information ID
pictInfoVerbErr	-11002	Invalid verb combination specified
cantLoadPickMethodErr	-11003	Custom pick method not in resource chain
colorsRequestedErr	-11004	Number out of range or greater than that passed to `NewPictInfo`
pictureDataErr	-11005	Invalid picture data

Summary of Pictures and the Picture Utilities

Pascal Summary

Constants

Data Types

Routines

Creating and Disposing of Pictures

Drawing Pictures

Collecting Picture Information

Application-Defined Routines

C Summary

Constants

Data Types

Functions

Creating and Disposing of Pictures

Drawing Pictures

Collecting Picture Information

Application-Defined Functions

Assembly-Language Summary

Data Structures

Picture Data Structure 0picSizewordfor a version 1 picture: its size 2picFrame8 bytesbounding rectangle for the picture 10picDatavariablevariable amount of picture data

Trap Macros

Trap Macros Requiring Routine Selectors

Picture Data Structure
0 picSize word for a version 1 picture: its size
2 picFrame 8 bytes bounding rectangle for the picture
10 picData variable variable amount of picture data